Copyright: 1998 © Visicom Media Inc


Introduction to CGI programs

The CGI (Common Gateway Interface) is a standard interface between an external Gateway application and the information on servers, such as a Web server.  A CGI program allows handling, obtaining and generating information based on data entered by the user.  In other words, the CGI program interprets information entered by the user and submitted to the Web server.

The type of information could be one of the following:

•	Information to search for, entered on the Web site’s search engines

•	Guestbooks, calendars or on-line calculators

•	Business transactions on line

•	Information found in data bases

•	Display in real time of information on the stock market, weather, and other rapidly changing information

•	The contents of a form

There are many types of CGI programs.  In this section we will mainly discuss:

1.	Using and installing the CGI Mailto program.

2.	Using and installing a counter (Hit Counter).

3.	Using and installing a guestbook.

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Using CGI to handle the contents of a form

Often, the mailto method is not recommended since not all browsers support it.  Besides, the contents of the form are returned in a format that is not easy to read.  The best approach is to use a CGI program that decodes the contents of the form and sends it by electronic mail.  The output returned is easier to read.  In this case, CGI could be described as a sort of interpreter between us and the form.

In order to run your own CG program, you must have access to a cgi-bin or cgi-shl directory on your server.  On the other hand, many users don't have access to this directory because their server restricts access to it.  However, most  servers provide access to the cgi-bin directory for an extra sum in the monthly rate.  Otherwise, it is necessary to use the utilities of the service provider.  The server should be able to furnish a common CGI to handle the forms of its users and to provide the necessary instructions.

CGI Mailto is  all rights reserved: Brian Dorricott : http://www.net-shopper.co.uk/

A commercial version with more features is available on his site.

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Using CGI Mailto

To use a CGI form, you must have an Internet account with access to CGI.  If you don’t have access, you cannot use this program.

You can find the Mailto.exe file in the following directory:

C:\Program Files\AceExpert3\CGI\Mailto\

The CGI Mailto program (shareware version) runs on servers using Windows NT.  The program does not run on servers that use the UNIX operating system,  This file must be placed in the server’s cgi-shl or cgi-bin directory.

CGI Mailto is  all rights reserved: Brian Dorricott : http://www.net-shopper.co.uk/

A commercial version with more features is available on his site.

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Description of Mailto

The CGI Mailto program allows the content of your formatted forms to be sent to one or more electronic mail addresses.  You can indicate the mail server name, the subject of the message and an URL address to display acknowledgement of receipt.

The following is a complete list of all possible fields:

Nom du champ	Description	Options
Sendto	E-mail address of recipient	Required
Cc	A list of e-mail addresses, separated by commas, of other recipients, if any	Optional
Server	The e-mail server	Uses the local host if non is specified
Subject	Subject or reference of message	Optional
Resulturl	The URL address of an HTML page to be displayed right after the message is sent
Resulttxt	Text of acknowledgement of receipt to be displayed
Uname	Name of the user that will be inserted in the from field of the message	Optional
Email	E-mail address of the person filling out the form.  The address will also be placed in the from field of the message	Optional


Example of Mailto's code
Example of Mailto’s code

<BODY>

<FORM ACTION="/cgi-shl/mailto.exe" METHOD=POST>
  <INPUT TYPE="hidden" NAME="sendto" VALUE="usager@visic.com">
  <INPUT TYPE="hidden" NAME="server" VALUE="mail.visic.com">
  <INPUT TYPE="hidden" NAME="subject" VALUE="Example of how to use CGI">
  <INPUT TYPE="hidden" NAME="resulturl"    VALUE="http://www.visic.com/merci.html">

Enter your information:

Name:	<INPUT TYPE="text" NAME="uname" SIZE=30 MAXLENGTH=30>

Title:	<INPUT TYPE="text" NAME="titre" SIZE=30 MAXLENGTH=30>

Company:	<INPUT TYPE="text" NAME="company" SIZE=40 MAXLENGTH=40>

E-mail:	<INPUT TYPE="text" NAME="email" SIZE=30 MAXLENGTH=30>

<INPUT TYPE="submit" VALUE="Submit">
<INPUT TYPE="reset" VALUE="Reset">

</FORM>

</BODY>
</HTML>

Please note that the fields sendto, server, subject, resulturl, uname and email are all used.  The values are assigned by fields hidden in the form.  The field ACTION runs the CGI.

Once the form is submitted, the CGI receives and decodes the content, it then reformats it and sends it to the address specified under sendto (and cc).  Immediately the acknowledgement of receipt page specified in the resulturl field is loaded.

The other elements are the items normally found on forms.


Installing CGI Mailto
Installing the CGI Mailto

Requirements:

In order to use this CGI you must:

•	Have access to your server’s cgi-bin or cgi-shl directory;

•	Use a server running under Windows NT.

Installation:

To install CGI Mailto :

1.	Find the Mailto.exe  file in the following directory:     C:\Program Files\ AceExpert3\CGI\Mailto\

2.	Copy the Mailto.exe file to your server’s cgi-bin or cgi-shl  directory.


Inserting CGI Mailto in your document

To insert CGI Mailto in your document, you must:

1.	Define the form sheet

2.	Insert form elements


Defining the form sheet

This is the first step in the development of your form.  The form sheet has two functions:

1.	The first function consists in delimiting the elements of the form.  This is needed so that the browser can identify where the form begins and ends, by reading the <FORM> and </FORM> tags.

2.	The second function consists in specifying the form’s parameters which are: name, action, send method, and type of encoding.  All these parameters must reside inside the <FORM> tag.

To define the form sheet with AceExpert:

1.	Select the Forms tab and click on the Form Definition  icon.

2.	The dialog window Form sheet  comes up.

3.	In the window Type of protocol, click on None (direct link).

4.	In the text box Action  enter: /cgi-shl/mailto.exe  or /cgi-bin/mailto.exe, depending in which directory you placed the mailto.exe file in your server.

5.	In the section Send Method, press the POST button.

6.	In the section Type of encoding, do not select any option.

The result is the following:

<FORM ACTION="/cgi-shl/mailto.exe" METHOD=POST>
  …

</FORM>


Inserting the form elements

Example

Before entering the fields that make up the usual items found in forms, it is important that you enter the fields: sendto, server, subject, resulturl.  These fields are handled by the CGI when the form is submitted and these specify the e-mail address of the recipient (sendto field), the server’s mail address (server field), the subject of the form (subject field) and the page that displays the acknowledgement of receipt (resulturl field).  The values in these fields are assigned with the help of fields hidden in the form.

To insert the sendto, server, Subject and  resulturl fields with AceExpert :

1.	Place the cursor between the tags <FORM ACTION="/cgi-shl/mailto.exe" METHOD=POST>  … </FORM>

2.	Select the Forms tab and click on the button Hidden entry.  The dialog box Form elements opens.

3.	In the text box Name, enter  sendto.

4.	In the text box Value,  enter the e-mail address where the message will be sent.

5.	Press the OK button.

6.	Repeat steps 2 through 5 to enter in the text box Name  the fields : server, subject and resulturl.  The corresponding values in the text box  Value are : the e-mail address of the  mail server,  the subject of the message  and the URL address that displays the acknowledgement of receipt.

After entering the form’s hidden fields, you can then enter the items that you want to displayed in your form. The different items you can enter are:

•	Check box

•	Radio button

•	List box

•	ComboBox

•	Text box

•	Password box

•	Text Area box (multi-line box)

•	Button

•	Submit button

•	Reset button

•	File attached

•	Form image


Placing a CGI counter on your page

A very common question is, How do I put a counter on my page?

To place a counter on your page, you have three alternatives:

1.	Use the counter supplied by your service provider.

2.	Use a counter provided by several sites.

3.	Use your own counter.

Use the counter supplied by your service provider

Some users cannot have a counter on their pages because their account does not include access to CGI.  In this case you should call your service provider who can generally indicate how to place a counter in your page.  However, the process is different depending on the features supported by your provider.

Usually this is the simplest way to place a counter on your page.  However, if you cannot obtain this service from your provider, then you can resort to available counter services.

Use a counter provided by another site

You can get a counter from a counter service (free or commercial) other than your service provider.

Use your own counter

You can use your own counter like the CGI Hit counter included in AceExpert.

CGI Hit Counter

All rights reserved: Ryan Terry Sammartino : http://www.geocities.com/SiliconValley/6742/

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Using the CGI Hit counter

To use a CGI form, you must have an Internet account with access to CGI.  If you don’t have access, you cannot use this program.

You will find the counter.exe file in the following directory:

C:\Program Files\ AceExpert3\CGI\Hitcounter\

The CGI HitCounter program runs on servers using Windows NT.  The program does not run on servers that use the UNIX operating system,  This file must be placed in the server’s cgi-shl or cgi-bin directory.

CGI Hit Counter

All rights reserved: Ryan Terry Sammartino : http://www.geocities.com/SiliconValley/6742/

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Installing the CGI Hit Counter

Requirements:

In order to use this CGI you must:

•	Have access to your server’s cgi-bin or cgi-shl directory (CGI compatible).

•	Use a server running under Windows NT.

Installation :

To install the CGI Hit Counter:

1.	Find the counter.exe  file in the following directory:     C:\Program Files\ AceExpert3\CGI\Hitcounter\

2.	Copy the counter.exe file to your server’s cgi-bin or cgi-shl  directory.

The following is the complete structure of Hit Counter once it’s installed:

/cgi-bin (ou cgi-shl)	<-- The directory where the CGI programs are kept on the server

        |

        |--counter.exe	<-- the CGI program

        |--counter.cfg	<-- the configuration file

        |

        |

        |--/digits	<-- Directory where the different types of counters are stored

              |

              |--/led	<-- counter style

                 |

                 |--0.gif

                 |--1.gif

                 |--2.gif

                    .

                    .

                    .

•	counter.exe – the counter (the  CGI program)

•	/digits/led/*.gif – the gifs used to display the counter

•	counter.cfg – the configuration file


Inserting the CGI Hit Counter in your page

Once the CGI Hit Counter is installed, the counter creates a file called counter.dat in the cgi-bin (or cgi-shl) directory that registers the number of visits to the site.  You then have to place the following HTML code for the counter in your page as indicated below:

<IMG SRC="/cgi-shl/count.exe?link=PageDev&style=timex&width=6">


Description of the Hit Counter
Description of Hit Counter

With the Hit counter you will know the number of visits to you page during a certain period of time.  When a visitor goes to your page,  a request is made to the resident CGI on your site’s server.  Generally, a log file is modified, and the number of hits is updated.

/cgi-shl/counter.exe? :	Executes the counter program on the server.
link :	Indicates the page whose hits are to be counted (it could be any name, it just indicates which counter goes with which page).
& :	Only used to separate options.
style :	Indicates the counter’s style.  The style must correspond with one found in the /digits directory located under the server’s cgi-bin or cgi-shl directory (e.g. Timex).  The styles represent gif images, digits 0 to 9. If the style equal to simple, no .gif will be used. This is useful to speed up the loading time of the counter.
width :	indicates the number of digits in the counter.  For example, you can have a counter with 3 digits (i.e. 125) or one with 7 digits (i.e. 1239645). By default the number is 4.
ord :	If ord=yes, an ordinal number will be outputted. An ordinal number is a number like 1st, 2nd, etc…. By default the value is no. If you use the ordinal number, 4 graphic files (st.gif , nd.gif, th.gif, rd.gif) must be present in the same directory of the other gif digits.
bgcolor :	If style=simple, specifies the background color of the image, or if style=trans is used, specifies a transparent background. The default is 000000 (black).
fgColor :	If style=simple, specifies the foreground color of the image. Same format as bgcolor. The default is FFFFFF (white).
Inc :	Specifies the increment number of the counter. Using 0 or a negative value will not increment the counter. If you are calling from a computer specified in the [No-Increment-For] section of counter.cfg, this argument has no effect.

You can insert the counter on as many pages as you like, and  all you have to do is modify the link option to insert a different page name.  In this way, you will know which pages in your site are more visited.  You can also hide the counter form the visitors (no one will see the counter) by assigning the value 1 to options width and height.


Example of Hit Counter's code
Example of Hit Counter’s code

1.	Example of code of the CGI Hit counter using the Timex style and displaying 6 digits:

<IMG SRC="/cgi-shl/count.exe?link=PageDev&style=timex&width=6">

Resulting code:

2.	Example of code of the CGI Hit counter using the Led style and displaying 8 digits:

<IMG SRC="/cgi-shl/count.exe?link=PageDev&style=led&width=8">

Resulting code:

3.     Example of code of the CGI Hit counter using no graphic (no .gif).

<IMG SRC="/cgi-shl/counter.exe?link=page3&style=simple&bgcolour=00FFFF&fgcolour=FF0000">

Description of the parameters used in the code:

/cgi-shl/counter.exe? :	executes the counter program on the server.

link :	indicates the page whose hits are to be counted (it could be any name, it just indicates which counter goes with which page)

& : 	only used to separate options.

style : 	indicates the counter’s style.  The style must correspond with one found in the /digits directory located under the server’s cgi-bin or cgi-shl directory.  The styles represent gif images, digits 0 to 9.

width :	indicates the number of digits in the counter.  For example, you can have a counter with 3 digits (i.e. 125) or one with 7 digits (i.e. 1239645).


Placing a CGI Guest Book on your page

What is a guest book? An electronic guest book on your web site is like a guest book in a museum or other tourist places. Visitors can leave messages and create links to their own homepages. You will get entries from your friends and other people from all around the world.

You have 2 alternatives to use a Guest book on your site:

Use a guestbook provided by another site

You can get a free or commercial Guest Book service available on the internet.

Use  your own CGI GuestBook

You can use your own Guest Book program like this CGI included in AceExpert.

CGI Guest Book

All rights reserved: Ryan Terry Sammartino : http://www.geocities.com/SiliconValley/6742/

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Using the CGI Guest Book

To use a CGI form, you must have an Internet account with access to CGI.  If you don’t have access, you cannot use this program.

You will find the book.exe file in the following directory:

C:\Program Files\ AceExpert3\CGI\GuestBook\

The CGI Guest Book program runs on servers using Windows NT.  The program does not run on servers that use the UNIX operating system,  This file must be placed in the server’s /cgi-shl or /cgi-bin directory.

CGI GuestBook

All rights reserved: Ryan Terry Sammartino : http://www.geocities.com/SiliconValley/6742/

Copyright ©1996-99 Visicom Média Inc.  All rights reserved. : http://www.visic.com


Installing the CGI Guest Book

Requirements:

In order to use this CGI you must:

•	Have access to your server’s cgi-bin or cgi-shl directory (CGI compatible).

•	Use a server running under Windows NT.

Installation :

To install the CGI Guest Book:

1.	Browse to the following directory:     C:\Program Files\ AceExpert3\CGI\GuestBook\HTML-install

2.	Copy the files bookform.html and book.html to your HTML document project directory.

3.	Edit the file bookform.html with AceExpert to change the HTML design as you wish.

4.	Edit the file book.html to change the "My Guest Book" sentence and write what you want to say.

Important: You should not add anything after the final <hr>.

5.	Browse to the following directory:     C:\Program Files\ AceExpert3\CGI\GuestBook\

6.	Edit the file book.cfg and under the [Bookmaster] section, put your e-mail address. Under the [Guest_Book_URL] section, put the URL to the file book.html. Under the [Guest_Book_Filename] section, put the full path to the file book.html. And finally, under [Homepage_URL] put your homepage's URL. Sample book.cfg file is provided in the description section.

7.	Copy the files book.exe and book.cfg file to your server’s cgi-bin or cgi-shl directory and book.html and bookform.html to your directory on your ftp site.

The following is the complete structure of Guest Book once it’s installed:

/cgi-bin (ou cgi-shl)	<-- The directory where the CGI programs are kept on the server

|

|--book.exe	<-- The CGI program

|--book.cfg	<-- The configuration file

/in your HTML project directory

|--book.html	<-- Guest Book

|--bookform.html	<-- The form people fill in

•	book.exe – the counter (the  CGI program).

•	book.cfg – the configuration file.

•	book.html – HTML Guest Book file.

•	bookform.html – The HTML form people fill in.

Important note: The guest book has to have read/write permissions in the /cgi-bin directory, as well as any directory where you want guest books kept.


Description of the CGI Guest Book

With the Guest Book CGI, you will let visitors sign, read and  write comments on your site. The guest book program creates files called book.dat where it keeps track of how many people have signed in and uses the file lock.boo as a semaphore.

Description of the book.cfg file:

[Bookmaster]

someelse@yourhost.com	<-- email address

[Guest_Book_URL]

/somedir/book.html	<-- book.html location

[Guest_Book_Filename]

c:\www\htdocs\somedir\book.html	<-- local book.html location

[Homepage_URL]

/somedir/index.html	<-- Home page


Example of Guest Book's code
Example of Guest Book’s code

1.	Example of code for bookform.html file:

<FORM METHOD="POST" ACTION="/cgi-bin/book.exe">
  Name:
  <INPUT Type="text" Name="theName" SIZE=35 MAXLENGTH="127">*<BR>
  E-mail:
  <INPUT TYPE="text" name="theEmail" SIZE=35 MAXLENGTH="127"><BR>
  Where are you from (city, state/province)?
  <INPUT TYPE="text" name="theCity" SIZE=35 MAXLENGTH="127">*<BR>
  If you have a homepage, please enter your URL here:<BR>
  <INPUT TYPE="text" NAME="theHomepage" SIZE=70 MAXLENGTH="127"><BR>
  How did you find us?
  <INPUT TYPE="radio" NAME="theWay" VALUE="Dumb luck" CHECKED>By luck
  <INPUT TYPE="radio" NAME="theWay" VALUE="Following this link:">Followed a link
  <BLOCKQUOTE><I>Please give URL here:</I><INPUT TYPE="text" NAME="theLink" SIZE=38 MAXLENGTH=256></BLOCKQUOTE>
  <INPUT TYPE="radio" NAME="theWay" VALUE="Using WebCrawler or other search engine">From WebCrawler or other search engine
  <INPUT TYPE="radio" NAME="theWay" VALUE="Word of mouth">Word of mouth
  <INPUT TYPE="radio" NAME="theWay" VALUE="Other means">Other means<BR>
  Any Comments?
  <INPUT TYPE="text" NAME="theComment" SIZE=70 MAXLENGTH=254>
  <P>
  <INPUT TYPE="submit" VALUE="Sign the Book"> <INPUT TYPE="reset" VALUE="Start Over">
  <P><I>* These fields must be filled</I>
</FORM>

2.	Example of code for book.html file:

<HEAD>
<TITLE>Our Guest Book</TITLE>
</HEAD>
<H1 Align="Center">Our Guest Book</H1>
<I>You may have to press Reload to get the most up-to-date version</I>
<hr>

Note: The file has to end by a <hr>